Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 016 / scrnstuf.arc / BURNOUT.DOC < prev next >

Wrap

Text File | 1986-02-24 | 25.2 KB | 568 lines

V2.01 22-Mar-1985 Burnout II Documentation ------------------------ Function -------- Burnout is an enhanced version of the old screen blanking program of the same name; its primary purpose is to blank out your video display after a specified length of time. This new version is signifcantly enhanced over the older program; not only does it allow you better control over its operations, but it is written as a virtual device driver so that you can control it directly from your own programs. V2.01 Notes ----------- The status report has been changed to be consistent with the format of input parameters. The new status report is: count,reset,B,C+,V+,H+ Note that count and reset have been reversed. This makes it possible to reset burnout's parameters by passing its own report back to it, beginning with the first character of the reset count. (The "B" will be ignored because it's not a valid parameter.) There is also a burnout "R" command which was present but not documented in version 2.00. There was an error in the V2.00 documentation, in which it was stated that you must send a "#" to BRNDEV to prepare it for a status request. This is not correct; the "@" flush character is sufficient. This error also cause the first BASIC demo program in the TRICKS section to malfunction. Line 40, which was 40 PRINT #1,"@#"; should have been 40 PRINT #1,"@"; Installation ------------ To install burnout, follow two steps: place the file BURNDEV.SYS in the root directory of your boot diskette or hard disk, and modify the CONFIG.SYS file to include the statement "device=burndev.sys". In case you are not familiar with CONFIG.SYS: this is a small text file which DOS reads when booting. It contains various pieces of information which DOS and other programs can use when setting themselves up. Look in the root directory of your boot disk for the file CONFIG.SYS. If no such file exists, just type: copy con \config.sys<Enter> device=burndev.sys<Enter> Then press Ctrl-Z (you'll see "^Z") and <Enter>, and you're done. If you already have a CONFIG.SYS file (which is likely), you must edit it to include the statement "device=burndev.sys". Do this using your text editor or word processor in text mode (or Edlin, heaven forbid). Retain all existing information, and add the new line. WARNING: version 2.0 is experimental. Don't install burnout on your only bootable disk. There's always a chance something will go wrong go wrong go wrong, and you can't delete the CONFIG.SYS or BURNDEV.SYS files unless you can boot the machine. Now reboot your machine. If all goes well, it will boot as usual. There will be no indication that anything has happened. However, the screen should blank out after about ten minutes of inactivity. Burnout parameters ------------------ There are several ways in which you can alter the operation of burnout. There is a demo program called BURNOUT.COM which you can use for this purpose. Its syntax is as follows: burnout [count] [V+-] [H+-] [C+-] The parameters are as follows: COUNT: changes the number of clock ticks until the screen blanks (this is called the "reset count"). For example, burnout 5000 sets the reset count to 5000. This means that if burnout observes no keyboard or video activity within 5000 clock ticks, it will blank the screen. On the IBM PC, there are about 18.2 ticks per second, so this means that the screen will clear after about 5000/18.2 seconds (275 seconds, or about four and a half minutes). (The default value on powerup is 10800 ticks, or about 10 minutes). You can set the reset count anywhere from 1 tick (not highly recommended) to 65535 ticks (about an hour). If you set the reset count to 0, burnout will be effectively "deinstalled" (equivalent to the old BURNOUT /Q) until you set a new nonzero count. This is useful for programs that don't get along with the screen blanker. V: This stands for Video, and tells burnout whether you want it to monitor video activity in adddition to keyboard activity. You can set either "V+" (monitor video), or "V-" (don't). Thus, burnout 5000 V- sets the program to reset to 5000 ticks, and not to monitor video. Why would you not want to monitor video? Primarily because some programs continuously update the display (e.g., with a ticking clock) even when they're not doing anything. If you set V+, the screen would never blank. The powerup default setting is V+. (V- is equivalent to the old "BURNOUT /K" command). H: This stands for Hardware, and tells burnout whether you want it to blank the screen by manipulating the hardware (i.e., by turning off the video signal), or by software (which it does by temporarily changing screen attributes to black-on-black, or nondisplay). Some explanation is in order. The preferred method of blanking the screen is to do it by manipulating the PC's video controller. This method is very fast and in general has fewer problems than the software method. However, it does have two problems. First, it is nonportable: it doesn't work with all PC-compatibles. Second, there have been reports that this method can PHYSICALLY DAMAGE a few non-IBM video adapters, notably the Hercules monochrome graphics adapter. DO NOT USE H+ IF YOU ARE USING A HERCULES VIDEO ADAPTER!!! YOU HAVE BEEN WARNED!!! If you are NOT using a Hercules card, try H+, with a setting of about 10 seconds, to make sure it works: burnout 180 H+ The screen should blank in about 10 seconds. If it does not, you will have to use H- (which is the powerup default setting). Reset burnout to some reasonable period of time, of course, after you have tested. C: This stands for Continuous Clear. If you are using H+, you can skip this one, because it is ignored in hardware blanking mode. As mentioned above, software blanking is achieved by simply changing all video attributes to nondisplay (black-on-black). Now, if you are running in V- mode (not monitoring video), or if you are running a program which achieves video output by writing data directly to screen memory, new data will begin to appear on the screen, even though it is blanked. Continuous Clear attempts to remedy this by simply resetting all the attributes to black-on-black every time the clock ticks (18 times per second). The new data will flash on the screen and disappear immediately. Powerup default is C-. Note that C- is equivalent to the old "BURNOUT /N" command. The burnout parameters can be entered in any order; illegal parameters, capitalization, and separators are ignored. Thus, the following are all equivalent: burnout 5000 V+ H- burnout 5000,V+,H- burnout v+h-5000 burnout H+, V-, 5000 burnout 5000H-V+ burnout h-5000v+ If you enter a count greater than 65535, you're on your own. You won't get what you expect. If you don't like the way BURNOUT.COM works, you're free to "roll your own"; see the next section. When BURNOUT has completed, it will display the current device status. For example: Status: 09994,10000, ,C-,V+,H+ The format of the status line is: Status: nnnnn,nnnnn,B,C+-,V+-,H+- The first number is the current number of clock ticks remaining till the next screen blank; the second is the reset count (in this case, the two numbers will be very close). The "B", if present, indicates that the screen is currently Blanked (you won't see this after running BURNOUT). The "C", "V", and "H" flags indicate the current status of Continuous Clear, Video monitoring, and Hardware clearing. If the parameter is active, the indicator will be followed by a plus sign (+), otherwise a minus sign (-). In the above example, then, the current count is 09994, the reset count is 10000, the screen is not blanked (naturally), Continous Clear is off, and Video monitoring and Hardware clearing are on. Unspecified parameters are not changed; thus, if you run burnout without any parameters, it will simply display status without changing anything. You can also include any of these parameters in the config.sys file so that they will be set immediately when you boot. For example, device=burndev.sys 8000 H+ V- Burnout command --------------- Burnout has one command, the "R" (reset) command. When the burnout device receives an R in its input stream, it performs two actions: it restores the screen if it is current blanked, and it resets the current count to the reset count. The R command's primary purpose is to allow other applications to force a burnout device reset, as described below. Using the BRNDEV device ----------------------- As mentioned above, the screen blanker is implemented as a virtual device. The advantage to this is that it can be interrogated or controlled very easily, from the DOS command line or from your own programs. In fact, BURNOUT.COM is a very simple program which takes your command line parameters, sends them to the burnout device, reads the current status back from the device, and displays the results. This section explains how to do this. When DOS finds the "device=burndev.sys" line in config.sys, it loads and installs the burndev.sys program as a virtual device. What this means, practically speaking, is that there is now a new "device" attached to your PC. You already have several devices installed: CON, PRN, COM1 and COM2, AUX, your disk drives, and possibly a RAM (or virtual) disk if you have installed VDISK.SYS or another disk emulator. The new device is known to DOS by the name "BRNDEV" (note: this is NOT "BURNDEV", it's "BRNDEV", no U). Like other devices, you can write (send information) to the device, and you can read (receive information) from the device. BRNDEV is designed to accept certain very specific information (the burnout parameters) when it is written to, and to return certain very specific information (the burnout status) when it is read from. Writing to BRNDEV ----------------- How do you "write" to BRNDEV? There are many ways. The simplest is to do it right from the keyboard, at the DOS prompt: copy con brndev<Enter> @8000 V-#<Enter> ^Z<Enter> The "copy con brndev" command instructs DOS that you want to copy input from the console device to the BRNDEV device. The console input "@5000 V-#<Enter>" is copied to the burnout device when you hit the Ctrl-Z (end of copy) and <Enter> (execute) keys. To prove it worked, type "burnout" and look at the new parameters; they should reflect a reset count of 8000 and no video monitoring. (The significance of @ and # will be explained shortly.) Another way to write to the device would be to copy a small textfile to BRNDEV. As an example, type copy con brndemo.txt<Enter> @10000V+#<Enter> ^Z<Enter> You should now have a small textfile, the contents of which are "@10000V+#". To sen it to BRNDEV, just type copy brndemo.txt brndev or type brndemo.txt > brndev Run burnout to prove that the parameters have changed. The purpose of the "@" at the beginning of the output to BRNDEV is to tell the device to flush or rewind its I/O buffers. BRNDEV just sees a sequence of characters coming from DOS; it has no particular way to know when it is getting a new sequence of command characters. The "@" tells it to get rid of any old, leftover junk and to start fresh. Make a habit of prefixing all BRNDEV commands with an @ symbol. "@" also has a second purpose, which will be covered below. The "#" is the "execute" character. It tells BRNDEV that it has received the whole parameter list. Only when BRNDEV sees the # will it examine the parameter list and execute the commands. Thus, "#" should be at the end of all BRNDEV commands; something like "@5000 C+H-" will have no effect at all. The one exception is that it is NOT necessary to send a "#" to execute a "@". That is, the "@" is a live character; it is not buffered for later execution. It is also possible, of course, to send commands to BRNDEV from high level languages or from assembler programs. Here's a BASIC example: 10 OPEN "BRNDEV" FOR OUTPUT AS #1 20 PRINT #1, "@5000 C+ H-#"; 30 CLOSE 1 And C (this is C86); you'd want to add some error detection: { FILE *burnout, *fopen(); static char command[] = "@5000 C+ H-#"; burnout = fopen("BRNDEV","w"); fwrite(command, 1, strlen(command), burnout); fclose(burnout); } For an 8086 assembler example, see the source for BURNOUT.COM (BURNOUT.ASM), which is included in the burnout library. Basically, you have to open the device (filename=BRNDEV, fomode 0 or 2), and use function 40H (FWRITE) to write bytes to the device using the returned handle. Note that application programs can use the R command to force a burnout device reset: 1000 ' SUBROUTINE TO RESET BURNOUT AND RESTORE SCREEN 1010 OPEN "BRNDEV" FOR OUTPUT AS #1 1020 PRINT #1,"@R#"; 1030 CLOSE 1 1040 RETURN Reading from BRNDEV ------------------- Unfortunately, reading from BRNDEV is not quite as simple as writing to it. There's no way that I can think of to do it from the command line; you really need a program (I suppose you could CTTY BRNDEV and then reboot when the machine went crazy [just kidding, don't try it]). Also, there is a bug in DOS 2.x which prevents you from using BASIC for this purpose (fixed under 3.0, however). Under 3.0, the BASIC program would be: 10 OPEN "BRNDEV" FOR OUTPUT AS #1 20 PRINT #1, "@"; ' Note "#" not necessary here 30 CLOSE 1 40 OPEN "BRNDEV" FOR INPUT AS #1 50 BSTAT$ = INPUT$(22,1) 60 CLOSE 1 70 PRINT "Burnout status is "; BSTAT$ Note that we always write an "@" to the device before reading its status. The @'s function is described as above, to flush any unfinished I/O from BRNDEV's buffers. Of considerable importance here, however, is that the @ also tells BRNDEV to prepare for a status request. When BRNDEV sees the @, it examines its current status and puts the data into a buffer, from which it will be retrieved when it gets the request. Without the preparatory @, you'll get old data. The significance of the "22" in the INPUT$ statement is that the BRNDEV status report is 22 characters long. Here's a C example: { FILE *burnout, *fopen(); static char command[] = "@"; char status[30]; burnout = fopen("BRNDEV","rw"); fwrite(command, 1, strlen(command), burnout); fread (status, 1, 255, burnout); fclose(burnout); printf("Burnout status is %s\n", status); } Note that we requested 255 characters. DOS, in general, will halt a device read when it encounters a carriage return from the input stream. BRNDEV makes a habit of sending a CR after the last byte of the status report, so this will terminate the read automatically; no need to worry about the true length of the report. BASIC, however, will just keep reading until it accumulates the requested number of characters, so you do have to be watchful there. The same trick (requesting too many characters) will also work in assembler programs (again, see BURNOUT.ASM). Now, about that bug in DOS 2.x. It turns out that DOS will mess up if you ever request a single byte from an installed character device, which is what BRNDEV is. (Technically: EOF is set on the device, and you will not be able to do any further reads unless you mess with IOCTL and explicitly reset EOF.) Thus, the following assembler code will NOT work under 2.x: mov cx,22 ; Loop for 22 bytes Label: push cx ; Save loop count mov ah,3FH ; Read from file mov bx,BHandle ; BRNDEV file handle (from FOPEN) mov cx,1 ; One byte at a time mov dx,offset buf ; Where to put the data int 21H ; Perform read (do something with the byte) pop cx ; Recover loop count loop label ; Loop till 19 bytes read The first byte will be read OK, but no further input will be received. You MUST read at least 2 bytes at a time. This bug can be overcome in assembler and C by simply requesting the full status report in one read. However, it appears that BASIC requests only one byte at a time, even if you use something like INPUT$(22,n). Reading the second byte then results in a READ PAST EOF error. Tricks ------ You can do neat stuff like waiting for the screen to burn out, then turning it back on: 1 REM DEMO PROGRAM TO WAIT UNTIL SCREEN BLANKS 2 REM 10 OPEN "BRNDEV" FOR OUTPUT AS #1 20 OPEN "BRNDEV" FOR INPUT AS #2 30 WHILE NOT BURNED.OUT 40 PRINT #1,"@"; 50 A$ = INPUT$(22,2) 60 BURNED.OUT = (MID$(A$,13,1) = "B") 70 WEND 80 BEEP: PRINT "Burned out!" 90 CLOSE 1: CLOSE 2 The 13th character of the status report, "B", will appear in the report only when the screen is blanked. Also, your programs can cancel burnout totally, if desired: 1 REM DEMO PROGRAM TO DISABLE BURNOUT 2 REM 10 OPEN "BRNDEV" FOR OUTPUT AS #1 20 PRINT #1,"@0#"; 30 CLOSE 1 (I am not a BASIC programmer, so if any of these demo BASIC programs are dumb, someone tell me.) Naturally, it would be possible (and friendly) to read in the burnout parameters, modify them while your program is running, and restore the original parameters when you are done. If you use Seaware's Extended Batch Language, you can even test whether or not BRNDEV is installed from within a batch: bat stateof BRNDEV bat if %r = 0 type BURNOUT IS INSTALLED | goto -A1 bat type BURNOUT IS NOT INSTALLED bat -A1 If you have a one-floppy machine, you can trick DOS and BAT into not checking the second logical drive (and stopping the batch to ask you to "Insert diskette for drive B") by using bat stateof A:BRNDEV DOS apparently doesn't care if you prefix a device name with a drive ID. Incompatibilities and Problems ------------------------------ I am aware of only a few problems and interactions with other programs. In order for burnout to "see" keyboard and video activity, active programs must use ROM BIOS (or DOS, which itself uses BIOS) for their keyboard input and video output. A few progams use neither; hence burnout never sees their activity, and the screen will be irrevocably blanked. These programs are mostly word processors; two that I know of are XYWrite and WordVision. You must disable burnout before using either of these ("BURNOUT 0" will do the trick). Most people do this in a batch: burnout 0 wv burnout 10000 There are also problems with some communications programs if you use software blanking. If you are performing an extended length file transfer the screen may blank during the transfer. Software blanking takes a little time, and communications input can be lost while it is being accomplished. This, of course, messes up the transfer. And Continuous Clear is even worse. The solution is either to use hardware blanking or to disable burnout while transfers are taking place. You MAY be able to get away with leaving burnout enabled, but disabling Continuous Clear (C-). Note that the word "BRNDEV" becomes a reserved word to DOS. You cannot name any file BRNDEV (or even BRNDEV.TXT, or whatever). DOS won't let you do that. If you do succeed, you won't be able to erase it. This is why the driver is stored in a file named BURNDEV.SYS rather than BRNDEV.SYS. Tick chart ---------- To save wear and tear on your calculator, here are some approximate tick counts: Minutes Count ------- ----- 1 1100 2 2200 3 3275 4 4375 5 5450 6 6550 7 7650 8 8725 9 9825 10 10920 20 21850 30 32760 40 43680 50 54600 60 65520 The Usual Suspects ------------------ The author accepts no responsibility for this software whatsoever. It might work, it might not. In particular, he accepts no responsibility for any result of the use of the software, even if it results in damage to your hardware. The burnout device driver (BURNDEV.SYS) and all demonstration programs are placed in the public domain and may be freely used by any individual. You may not use them commercially. You may copy and distribute the software and documentation to any other individual, PROVIDED that you do not charge for this. Recognized users' groups may, however, charge a small fee for postage and materials. I am interested in comments or suggestions on the usability of the burnout system, especially by programmers. Contact me via CompuServe if possible. All software and documentation are Copyright (c) 1985 by Christopher J. Dunford 10057-2 WIndstream Drive Columbia, Maryland 21044 CompuServe ID 76703,2002